 /*
  * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPEventListener.java,v 1.8 2006/06/16 16:31:46 hargrave Exp $
  *
  * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.osgi.service.upnp;

 import java.util.Dictionary ;

 /**
  * UPnP Events are mapped and delivered to applications according to the OSGi
  * whiteboard model. An application that wishes to be notified of events
  * generated by a particular UPnP Device registers a service extending this
  * interface.
  * <p>
  * The notification call from the UPnP Service to any <code>UPnPEventListener</code>
  * object must be done asynchronous with respect to the originator (in a
  * separate thread).
  * <p>
  * Upon registration of the UPnP Event Listener service with the Framework, the
  * service is notified for each variable which it listens for with an initial
  * event containing the current value of the variable. Subsequent notifications
  * only happen on changes of the value of the variable.
  * <p>
  * A UPnP Event Listener service filter the events it receives. This event set
  * is limited using a standard framework filter expression which is specified
  * when the listener service is registered.
  * <p>
  * The filter is specified in a property named "upnp.filter" and has as a value
  * an object of type <code>org.osgi.framework.Filter</code>.
  * <p>
  * When the Filter is evaluated, the folowing keywords are recognized as defined
  * as literal constants in the <code>UPnPDevice</code> class.
  * <p>
  * The valid subset of properties for the registration of UPnP Event Listener
  * services are:
  * <ul>
  * <li><code>UPnPDevice.TYPE</code>-- Which type of device to listen for events.
  * </li>
  * <li><code>UPnPDevice.ID</code>-- The ID of a specific device to listen for
  * events.</li>
  * <li><code>UPnPService.TYPE</code>-- The type of a specific service to listen
  * for events.</li>
  * <li><code>UPnPService.ID</code>-- The ID of a specific service to listen for
  * events.</li>
  * </ul>
  */
 public interface UPnPEventListener {
     /**
      * Key for a service property having a value that is an object of type
      * <code>org.osgi.framework.Filter</code> and that is used to limit received
      * events.
      */
     static final String UPNP_FILTER = "upnp.filter";

     /**
      * Callback method that is invoked for received events.
      *
      * The events are collected in a <code>Dictionary</code> object. Each entry
      * has a <code>String</code> key representing the event name (= state variable
      * name) and the new value of the state variable. The class of the value
      * object must match the class specified by the UPnP State Variable
      * associated with the event. This method must be called asynchronously
      *
      * @param deviceId ID of the device sending the events
      * @param serviceId ID of the service sending the events
      * @param events <code>Dictionary</code> object containing the new values for
      * the state variables that have changed.
      *
      *
      */
     void notifyUPnPEvent(String deviceId, String serviceId, Dictionary events);
 }

